audit: bead/mcb-o96i-16-hook-commit-recovery-v3 -> main - #166

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/lib/workspace_command.py, line 20:

<comment>Every dispatcher invocation fails at import when its required `toml` package is not preinstalled; declare and provision this runtime dependency for the workspace Python environment.</comment>

<file context>
@@ -0,0 +1,778 @@
+from pathlib import Path
+from typing import NoReturn
+
+import toml
+
+from lib.workspace import (
</file context>

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/lib/mcb.sh, line 137:

<comment>Commits that stage Cargo.toml/Cargo.lock will fail the staged check. When a manifest/lockfile is staged, `packages` is set to `--workspace` and fed to `cargo fmt $packages -- --check`, but `cargo fmt` does not accept `--workspace` (only `-p/--package` and `--all`), so it exits 2 and the pre-commit gate aborts. `cargo clippy` does accept `--workspace`, which is why the mismatch only surfaces on the fmt call. Use a scope flag that both tools accept (e.g. `--all`) or split fmt/clippy scoping.</comment>

<file context>
@@ -77,6 +125,38 @@ mcb_validate() {  # $1 = "quick" | "full"
+  [ -n "$staged" ] || { mcb_ok "staged check: no staged paths"; return 0; }
+
+  if printf '%s\n' "$staged" | grep -qE '^Cargo\.(toml|lock)$'; then
+    packages="--workspace"
+  else
+    while IFS= read -r path; do
</file context>

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/lib/mcb.sh, line 155:

<comment>The pre-commit gate validates unstaged working-tree contents rather than the staged snapshot, allowing invalid staged Rust to pass after an unstaged local fix; run checks against an index materialization or reject relevant unstaged changes.</comment>

<file context>
@@ -77,6 +125,38 @@ mcb_validate() {  # $1 = "quick" | "full"
+
+  [ -n "$packages" ] || { mcb_ok "staged check: no Rust package affected"; return 0; }
+  mcb_log "staged check: cargo fmt/clippy scope:$packages (deadline ${deadline}s each)"
+  timeout --signal=TERM --kill-after=5s "${deadline}s" cargo fmt $packages -- --check
+  timeout --signal=TERM --kill-after=5s "${deadline}s" cargo clippy $packages --all-targets -- -D warnings
+  mcb_ok "staged check: clean"
</file context>

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/lib/mcb.sh, line 81:

<comment>`make sub WHAT=sync` loops forever on POSIX `/bin/sh` systems because `git submodule foreach` cannot execute Bash's `read -d`; use a POSIX-compatible path reader or explicitly invoke Bash for this pipeline.</comment>

<file context>
@@ -51,6 +51,54 @@ mcb_retry() { local n="$1" s="$2"; shift 2; local t=1; while ! "$@"; do [ "$t" -
+
+  while :; do
+    materialized="$(git -C "$repo" submodule foreach --quiet --recursive '
+      present="$(git ls-files -z | while IFS= read -r -d "" path; do
+        if [ -e "$path" ] || [ -L "$path" ]; then
+          printf 1
</file context>

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/lib/mcb.sh, line 82:

<comment>A submodule with one remaining tracked file is treated as materialized, so `sync-submodules` leaves other deleted tracked files missing; check every indexed path and restore only missing paths to preserve local edits.</comment>

<file context>
@@ -51,6 +51,54 @@ mcb_retry() { local n="$1" s="$2"; shift 2; local t=1; while ! "$@"; do [ "$t" -
+  while :; do
+    materialized="$(git -C "$repo" submodule foreach --quiet --recursive '
+      present="$(git ls-files -z | while IFS= read -r -d "" path; do
+        if [ -e "$path" ] || [ -L "$path" ]; then
+          printf 1
+          break
</file context>

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/hooks/pre-commit, line 10:

<comment>Published pre-commit instructions still promise lint and architecture validation; update them to describe the staged-only gate so developers do not rely on checks this hook no longer runs.</comment>

<file context>
@@ -1,11 +1,11 @@
 echo "→ guard (staged)…";   bash scripts/lib/mcb.sh guard --staged
-echo "→ lint…";             make check WHAT=lint
-echo "→ validate (quick)…"; make check WHAT=validate QUICK=1
+echo "→ staged check…";      make check WHAT=staged
 echo "✓ pre-commit passed"
</file context>

Check if this issue is valid — if so, understand the root cause and fix it. At Makefile, line 39:

<comment>The new check phases (staged/hooks/guard) are not reflected in AGENTS.md/README.md, which still list check WHAT as fmt|lint|validate|audit|udeps|coverage|qlty|all. Since those docs are embedded as agent/reviewer context, updating them keeps the documented surface in sync with the fact that the phases already work here.</comment>

<file context>
@@ -36,7 +36,7 @@ export RUST_2024_LINTS := -D unsafe_op_in_unsafe_fn -D rust_2024_compatibility -
 
 # --- WHATS_<verb> phase SSOT (drives sub-help + error arms) -------------------
-WHATS_check   := fmt lint validate audit udeps coverage qlty all
+WHATS_check   := fmt lint staged validate audit udeps coverage qlty hooks guard all
 WHATS_fix     := fmt lint docs all
 WHATS_dev     := run docker-up docker-down docker-logs docker-test
</file context>

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/lib/tests/test-hooks.sh, line 71:

<comment>The `timeout` stub's `*[smhd]` pattern swallows any argument ending in s/m/h/d, not only the duration token. It only works because `cargo` is always the first word after the timeout options, so consider narrowing the match to duration-shaped args (e.g. `*[0-9][smhd]`) so a future reorder or option doesn't silently drop a real argument and skew the log assertions.</comment>

<file context>
@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --signal=*|--kill-after=*|*[smhd]) shift ;;
+    *) break ;;
+  esac
</file context>

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/hooks/pre-push, line 1:

<comment>The new pre-push source file is committed without the executable bit (mode 644), unlike scripts/hooks/pre-commit (755). The installer chmods the installed copy so the primary path works, but any direct execution of the in-tree hook (e.g. core.hooksPath pointing at scripts/hooks, or invoking it manually/from CI) silently fails; set the executable bit on the committed file to match pre-commit.</comment>

<file context>
@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Installed by `make setup WHAT=hooks`. Runs the canonical full gate before
+# push, then preserves Beads hook processing when available.
</file context>

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/lib/workspace_command.py, line 185:

<comment>This statement is a no-op: it calls `os.environ.get("WHAT", "").strip()` and discards the result. It looks like a leftover line from an earlier help-rendering draft, and the very next line returns 0, so this has zero effect. Safe to delete.</comment>

<file context>
@@ -0,0 +1,778 @@
+        if args and args[0] == "--validate":
+            return 0
+        if not args or args[0] in {"help", "--help", "-h"}:
+            os.environ.get("WHAT", "").strip()
+            return 0
+        return dispatch(registry, args[0])
</file context>